Actions Tree
=====================

A actions tree is an object constituted of nodes, representing all the actions exchanged (performed) beetween server and clients.

For example, let's assume that we want to handle the communications of a basic chat program. Let's make a tour of the possibilities :
    * the clients can emmit a public message
    * the clients can also emmit private message, that only one person should see

Of course, this implies that:
    * the server relay public messages to everybody
    * the server relay private messages to the reciever only
    * the clients recieve message from server

Now we know all the actions that will be exchanged, we can represent the actions tree as below : ::

    Tree
        client
            message
                public
                private
        server
            message


Composition
----------------

Actions trees are composed of only one type of object, the :class:`Node` . But regarding their position in the tree, they do not fullfill the same role. There is three roles :
    * root : the base of the tree
    * node : act as a branch (or node if you feel more comfy with this image)
    * action : the leaves of the tree, they are the very end of it

Let's take back the tree example above, and see what role the different nodes have :

|    Tree - *root*
|        client - *node*
|            message - *node*
|                public - *action*
|                private - *action*
|        server - *node*
|            message - *action*


The two important roles are the *root* as it has access to all its children, and the *action* as it is to it we associate encoders and handlers


Accessing a :class:`Node` inside a tree
-------------------------------------------------------

Let's stay in our example, and assume the tree is already built and assigned to the name 'tree' : ::

    >>> #to access to the action private
    >>> tree.client.message.private
    < Node object at 0x0000000002C2EE80>

Each :class:`Node` is an attribute of its parent. This mechanism is keystrokes economic, clear and readable despite being also a bit unconventional.

Behind the scene
--------------------

The "magic" is awfully simple : each :class:`Node` (except the *root*) holds an automatically assigned bytecode.
When passing an :class:`Node` instance to the built-in :func:`str`, you obtain a string of bytecodes. The last one, is the one attributed to the :class:`Node` instance, the one before it comes from its parent, etc...

within our example : ::

    >>> str(tree.client.message.private)
    '\x00\x00\x01'

    >>> str(tree.server.message)
    '\x01\x00'